All NetCloak configuration is done using the CGI application, even if you are using the plug-in version of NetCloak. If you are using the plug-in, you must quit your Web server while performing NetCloak maintenance for the changes to take effect immediately. In general, NetCloak configuration is a very quick process, and your server need only be down for a minute or two when performing most maintenance tasks.

Configuration Window

NetCloak, like your Web server, serves files from a root folder. In fact, NetCloak can be configured to serve files from the folder selected by your Web server, which is particularly useful when using a server that supports multi-homing and passes the root folder information in the CGI AppleEvent or WebSTAR API request. Also like your Web server, NetCloak supports default, error and no access pages that can be defined for serving in error or restricted access circumstances. Finally, NetCloak can use a dynamic caching scheme to improve server performance.

To set these root folders, files, and preferences, open the Configuration window by selecting the "Configuration..." option of the "Configuration" menu.

Files Tab

The first tab of the Configuration window allows you to set the file and related defaults.

Root Folder

Choose the folder NetCloak should serve files from. To select the folder, click on the "Root Folder" button and choose the folder with the standard file dialog box that appears.

The root folder selected in the Configuration window is used as the root folder for all commands which accept a relative path, including macros, back-end CGIs and NetCloak aliases.

In most cases, the root folder will be the same folder as your Web server root folder. The ability to select the root folder has two important advantages. First, when using the NetCloak CGI, this allows you to put the CGI application anywhere you wish, for example, in a "cgi-bin" folder, while serving from the Web server root. In addition, the NetCloak root folder is not required to be the same as the server root folder. For example, if you are concerned about security, you can put your NetCloak files into a separate folder hierarchy from the main server folder structure. This will ensure that files that are supposed to be cloaked are never inadvertently served by your server without NetCloak processing them. Since the cloaked files will be outside of your Web server folder, the server will never be allowed to serve them.

Important Note: This assumes you are running a server that restricts access to a Web server root folder and that you have not placed any Finder aliases in your server root folder that would permit access to the NetCloak -defined root folder. It also does not take into consideration other CGIs that might be able to serve files outside the Web server root.

Figure 2: The Files tab of the NetCloak Configuration window.

Ask Server For Root Folder

If the server supplies a root folder as part of the CGI AppleEvent or W*API request, and this option is checked, NetCloak will disregard the defined root folder and serve from the folder specified by the Web server. Many web servers support this parameter, and selecting this option is the best way to ensure seamless file services when using NetCloak in conjunction with your server. This is especially true of servers that support multiple root folders for different domains. In this case, the folder to serve from may be different for each request that is processed by NetCloak. When this option is checked, NetCloak will always serve the file from the appropriate folder, as intended.

Note that when this option is checked, NetCloak will use the root folder specified by the server for each request that it receives. NetCloak will still use the folder selected with the "Root Folder" button to interpret relative paths for NetCloak aliases and other paths that it is not processing as part of a connection request.

Default, Error and No Access Files

There are three special files NetCloak requires to handle certain HTML requests.

Default Page: The name of the page NetCloak will look for when the user specifies only a directory (including the root domain). For example, if the default page is set to "HomePage.html", then NetCloak will look for that filename by default when only a directory is specified by an incoming URL request.

Error Page: When NetCloak is unable to find a file that matches an incoming URL, the Error page is returned. The error file can be specified as another CGI application, in which case NetCloak will call the CGI to handle the bad request.

No Access Page: The "No Access" page is returned when a user is denied access to a page because their IP address is denied or because they fail to enter a correct username and password for a password protected page.

Ask WebSTAR

The three special files are also set within WebSTAR (as well as most other server applications), so NetCloak can automatically retrieve the file information directly from WebSTAR by clicking this button. If you are using another Web server this button will not work, and you will have to set the file names manually.

Use Dynamic Caching

NetCloak supports a dynamic file cache that will automatically store your most frequently accessed files in RAM for faster retrieval and serving. The files NetCloak will store in RAM are selected based upon the amount of available RAM and the frequency with which files are accessed. To disable this feature, uncheck this box.

Logging Tab

NetCloak can maintain a log in addition to the one created by your Web server. Information included in the basic log is date and time of the request, status, the user's IP address or domain, the file requested, and the size of the response. The NetCloak extended log adds the username, password, referrer, and browser type. This extra information is added at the end of each line, so it should not interfere with log analyzing programs that expect only basic information.

Figure 3: The Logging tab of the NetCloak Configuration window.

One advantage to using the NetCloak log is that it will log only your HTML pages. When a client requests a page with multiple images on it, your Web server log will contain several entries, one for the HTML page and another for each of the images linked into the page. This redundancy is often unneeded, and causes your log files to quickly become very large. In addition, the Web server incurs the overhead associated with logging each page served multiple times.

By shutting off your Web server log, server performance will improve and your logs will be more manageable. The NetCloak log can then be used to show you who has visited your site and when. Of course, NetCloak will only log those file requests that it processes, so be aware that some site access will not be logged at all. This may not be appropriate for all Web sites, but for those whose logging requirements aren't as strict it is an excellent way to improve performance and simplify site management.

To set logging preferences, choose the "Logging" tab of the Configuration window.

You can choose whether to maintain a standard log, an extended log, or skip logging entirely. You can also choose to store the log information anywhere on your hard drive by clicking the "Log File" button and selecting a file to keep the log.

HTTP/ HTML Tab

Figure 4: The HTTP/HTML tab of the NetCloak Configuration window.

NetCloak supports several features that allow you to improve how your server behaves in different situations and for different browsers. To select these preferences, use the "HTTP/HTML" tab of the configuration window.

Server Name

The "Server Name" field is used by NetCloak to build the HTTP header returned to the client, and tells the client what server software is being used. The server name can be important for several reasons, and you should set this field carefully.

First, this field is used by many Web crawlers (also known as "robots") for studies that determine what software is being used by whom on the Internet. By correctly returning the name of your server, you are helping to promote the Mac OS platform and the server software you have chosen. This is not a trivial issue, and we strongly urge you to enter the correct name of your server software and the name "NetCloak". If you choose, you may list the names of other server applications, and they should be listed in order of importance, with the server itself always listed first.

It is not necessary to include the version numbers of the server, NetCloak, or any other server application. In fact, for security reasons, it is a good idea to leave the version number off. However, if you like, you may list the version numbers. If you choose to do this, the version number should follow the name of the application, with a slash ("/") between them, and no spaces. For example, you could set this field to:

     WebSTAR/2.1 NetCloak/2.5

Complete information on the server field can be found in the HTTP/1.1 specification, RFC 2068, section 14.39.

Last Modified

Another field of the HTTP header is the "Last-Modified" date of the file. This field presents special issues when using NetCloak, because NetCloak is constantly changing the contents of files. However, it is important to use this field so that proxy servers, and the browser itself can correctly cache cloaked pages.

To solve this problem, there are three options:

Exclude From Header: When you select this option, NetCloak will not include the Last-Modified field in the header at all. This is a legal option, and is provided for in the HTTP specification. By choosing this, you are essentially leaving caching decisions up to proxies and browsers that access the page.

Send File's Modified Date: If your site does not make excessive use of NetCloak's dynamic commands, your best option is to return the actual date the last time the file was modified. This is the same thing your server would do if the file was being served without NetCloak. Please note, however, that this will cause browsers and proxies to cache the page, and dynamic elements of your pages may not change as intended because of the caching.

Send Current Date/Time: For pages that are very dynamic, and that should always be loaded from the server, use the "Send Current Date/Time" option. This will always send the date and time that the page is being served as the files last modified date. This may seem like a trick, but it is the most reasonable setting, in many cases. NetCloak modifies files as they are being served, so reporting the current date and time is, in fact, accurate.

Note that this default setting can be overridden on a page by page basis using the NETCLOAK configuration command within your pages. You might want to do this if most of your pages are relatively static, with only a couple of very dynamic pages used on your site. In this case, you could set the default to "Send File's Modified Date" but use the NETCLOAK command to send the current date and time for the very dynamic pages.

Character Conversion

NetCloak will convert Mac-Roman extended characters to ISO-Latin-1 character encoding or HTML entities. For US-ASCII only Web sites, leave this option on "No Translation", but if you use extended characters, you can select an appropriate translation and edit your documents using the standard Mac OS character set. When these pages are served, the characters will be converted as specified so that they appear correctly in the user's browser, regardless of the platform or operating system they are using.

For all of the HTTP/HTML options, the only way to know for sure what will work best for you is to test your site with a variety of browsers. There is (unfortunately) a wide variety of ways in which browsers treat extended characters, as well as the caching of pages based on the last-modified date. Decide what browsers are important to support at your site, download them, and try the various options to make your site behave exactly the way you want.

Security Tab

NetCloak provides several security options designed to make your server as secure as you need it to be while giving you flexibility that is not possible with your Web server alone. Much of NetCloak's security benefits are found in the commands themselves, but there are also several options you can select from on the "Security" tab of the Configuration window.

Figure 5: The Security tab of the NetCloak Configuration window.

Only serve files listed in "NetCloak.config"

When this option is checked, NetCloak will not serve a requested file unless it is aliased by a line in the "NetCloak.config" file. This represents the ultimate level of security provided by NetCloak. In this mode of operation, users visiting your web site can only see aliased files, and the aliases used in your URLs can give the illusion of an entire folder hierarchy that doesn't even exist! By default, this option is not checked, allowing any files accessible by your web server software to be cloaked.

See the section NetCloak Aliases and Caching for information on NetCloak aliases.

Only process macros listed in "NetCloak.macros"

Because MACRO commands may refer to files located anywhere in your web server's folder heirarchy, malicious users may attempt to gain access to sensitive files on your server by submitting files which contain such MACRO commands. To eliminate this possibility, you can check this option. When checked, you have complete control over which macros may be executed on your server -- only those macros entered into the "NetCloak.macros" file will be allowed to run. By default, this option is checked. Users upgrading from NetCloak 2.0 or 2.1 who use MACRO commands to "include" pages within pages will need to un-check this option.

If NetCloak is unable to insert a macro because this option is checked, it will insert an error message enclosed in an HTML comment in place of the MACRO command when the document is served.

Prohibit EXEC_CGI tags

This option is fairly straightforward. When checked, NetCloak will not process EXEC_CGI commands. The EXEC_CGI command poses a security risk because malicious users may attempt to upload CGI files to your server and then call these CGIs by uploading HTML files containing EXEC_CGI commands. Or they may attempt to use your existing CGIs in a destructive manner. By default, this option is checked. To enable EXEC_CGI commands on your server, you must un-check this option.

If this option is checked, NetCloak will insert an error message enclosed in an HTML comment in place of the EXEC_CGI command when the document is served.

Short Time Menu Option

When the "Short Time" menu option is checked in NetCloak, all times inserted by NetCloak commands such as INSERT_TIME will be shown as hours and minutes, without seconds. When "Short Time" is not selected, times will be displayed with seconds. The time format will otherwise be as selected in the Mac OS Date & Time control panel on the server.

Figure 6: The NetCloak Configuration Menu Short Time option.

Short Date Menu Option

When this option is checked, INSERT_DATE and other NetCloak commands that insert dates will insert the date using the Short date format as defined in the Mac OS Date & Time control panel on the server. See the Date and Time control panel's "Date Formats" setting to configure the short and long date formats.

Configuration Outside Of NetCloak

There are a few configuration items outside of NetCloak that have an effect on how some NetCloak commands behave. These affect DOMAIN command parameters and how NetCloak commands display dates and times.

Web server option to look up client names

Most Web servers support an option to look up the domain name corresponding to the client IP address for each connection. Such an option is usually named something like "Look up client names", "Perform DNS lookups" or "Use DNS". You probably want the "Use DNS" option to be off in your Web server. This will speed up your server, but more importantly makes the server pass the TCP/IP address of the user to NetCloak without trying to resolve the machine name. This setting affects the DOMAIN commands in NetCloak. If "Use DNS" is off, NetCloak will expect numeric IP addresses (like "198.85.68.67") as the parameters in HIDE and SHOW_DOMAIN commands, and the INSERT_DOMAIN command will insert the client's IP address. If "Use DNS" is on, DOMAIN commands will use domain names, like "maxum.com" instead of IP addresses.

Date & Time control panel format setting

The INSERT_TIME and INSERT_DATE commands will display the time and date using the format selected in the Date & Time control panel on the server. Also, parameters to the HIDE_DATE and SHOW_DATE commands must match the short date format set in the Date & Time control panel. Make sure that the time and date formats are set according to how you would like them displayed on your pages. Since the date and time functions of NetCloak rely on the server's system clock, make sure the time and date are accurate.

Adjusting Internal Settings (Advanced Users Only)

This section is for advanced users whose system exceeds the limitations imposed by NetCloak on HTML file size, back-end CGI response timeouts, or the maximum number of counters available; and who have experience using a resource editor. In the vast majority of cases, you will never need these instructions.

NetCloak stores the default values for three operational parameters inside 'MaxP' resources in the resource fork of the ACGI and the plug-in. Refer to the table below for details on how NetCloak uses these resources.

If you need to edit these resources, please take the usual precautions when using a resource editor like ResEdit: always make a duplicate copy of the file to be edited, edit the copy of the file, save it and test your changes before throwing away the original and renaming the copy.

If you want NetCloak to process any HTML file which is larger than 128Kb, you must increase the "HTML Buffer Size" value stored in 'MaxP' resource ID 200. On the other hand, if you need to conserve memory, and you know you will never "cloak" an HTML file that is 128Kb, you can safely decrease the "HTML Buffer Size" value.

When you change the "HTML Buffer Size" value, you should also change the memory requirements of the Web server application (if using the plug-in) or the ACGI by the same amount, using the Finder's "Get Info" command.

You might need to change the "CGI Timeout" value if you have set up "back-end" CGIs or use EXEC_CGI commands, and your users often see the message "NetCloak Error: The back-end CGI did not respond to the request from NetCloak." returned to the browser. This might mean that the CGI is taking longer to return its results than NetCloak expects.

If you find that you need more than 512 counters, you can increase the "Max Counters" value in 'MaxP' resource ID 203. Or if you are sure you will never need that many counters, and you want to conserve memory, you can decrease this value.

When you change the "Max Counters" value, you should also change the memory requirements of the web server application (if using the plug-in) or the ACGI using the Finder's "Get Info" command. For each counter you add/remove, you should increase/decrease the memory requirements by 40 bytes. For example, if you want to increase from 512 to 1024 counters, you should increase the memory requirements by 40 x 512 = 20480 bytes = 21K.